Welcome to the Internet Relay Network, Macintosh User!
ircle is an IRC client program that lets you talk with people all over the world via the IRC (Internet Relay Chat) network. All you need is a Macintosh with a network connection and the MacTCP driver, and you have to be able (technically) to connect to an IRC server.
This manual has been split into two files because of the TeachText file size limit.
Contents:
part 1:
Getting Started
The Server
ircle Windows and Messages
Commands
CTCP and DCC commands
part 2:
ircle Menus
Further Reading
Beware of Pitfalls
What is still to be done
The inevitable legal stuff
Credits
NOTE to users of older versions of ircle: The preferences file handling has been changed. See just below.
Getting Started
--------------
Maybe you know already IRC. You might have used it from a Unix, VMS, or VM machine, probably using Telnet from your Mac to log in to that machine. Then you hopefully will have little doubt about how to use ircle, and you may as well skip this manual and just try it out. You will notice that there are probably many windows, one of them per channel you're on, and that you switch channels by just switching windows; that you have the most important commands available on shortcut keys, but you can use all commands like in a text-only environment too.
To all others who don't know IRC it is here to be explained what data they have to enter into the fields of the dialog which will be presented to them after they start the program.The settings are the following:
- Server: The hostname or IP address of your server. See below on more information.
- Port: The port number of your server. By now, the port used by IRC servers should always be 6667, but a different number can be entered in case there are special applications such as site-specific local servers that use a different port. Usually you don't have to worry about this.
- Nickname: Your most important user-specific thing. This is the name by which you will be known to other people on IRC, as each line of text you send to the network will on other users' screens be prefixed by your nickname. Choose a name that you like, and that consists of printable characters with no spaces and is at most 9 characters long.
But be aware of the fact that no two people on the network may use the same nick at one time. You will be presented an error message if a collision occurs and may not proceed until you have chosen another nickname (see below on the appropriate commands). Also be aware of the NickServ, which is a database that holds the nicknames of regular IRC users and will inform you if you have chosen a nick that has been registered by some other user. Nicknames are not owned, but it is considered bad behaviour to ignore NickServ and proceed with some other user's nick. NickServ will inform you about how to register your own nick too.
- E-Mail address: When IRC was Unix-specific, the servers kept track of users by their login names. However, on a machine (Mac or MSDOS) without user logins, this is senseless, but the server needs this information. As it can also be used by other IRC users to figure out who you are (to send you mail, for example), you should enter a valid account name (provided you have one, which is assumed to be the case if your site is Internet-connected :-) Some servers try to verify this name; in this case the name you give will appear to other users with a ~ prepended, but this doesn't hurt.
NOTE that if you pass an address of the form person@site.domain, the server will ignore the part after the @ and replace it with the actual machine it is called from, in this case of the Mac, and the /whois command will give the wrong address person@Mac.domain (with Mac replaced by the name your Mac is assigned) or sometimes person@1.2.3.4 (with a raw IP address). Nevertheless this information is valuable, see below on the /ctcp finger command.
- User name: This should be your real name but most people add comments to that name. Not too long a line, please :-)
- Notifications: ircle is able to run in the background (under System 7 or MultiFinder), and it can have more than one conversation window, so it is convenient to get notified of the fact that something happens in a background window. You may choose which notification you would like in which situation, from a flashing icon in the menu bar and a sound being played.
After having specified these parameters, you should save them to a preferences file. This can be done with the "Save Set" command from the File menu. This will create a file which contains these settings, along with information about currently opened windows, joined channels (s.b.) and other commands. This file can be double-clicked to start up your next IRC session. You can edit this file with a text editor and append commands (at the bottom only!) which will be executed on startup, like /notify or /ignore commands. This is very similar to the NCSA Telnet "set" files. If you have used older versions of ircle, your old Preferences files (which are in a different format) is read, but if you save the settings a new-format file will be generated.
The Server
----------
The IRC network consists of a number of servers all over the world, which are interconnected, and clients that can connect to these servers. To use IRC you have to know the address (hostname or IP number) of a server which you can use, and this should be the server which can be reached from your site at minimum delay and network load (usually the geographically closest).
The simplest case for finding a server is when you or some other people at your site have already used IRC: look at the screen when the connection is started. The server will give its name with the welcome message:
*** Your host is server-name [full-host.name], running version xxxx.
Enter the full host name into your preferences dialog.
Or you ask one of the local network gurus, who probably will know a server address, especially in big organizations which probably have a server themselves.
If that doesn't work, follow the method suggested by Helen Trillian Rose (in the file 'IRC Advice', which you should read completely anyway). A complete list of servers gets sometimes posted in the alt.irc newsgroup.
NOTE that you need the technical possibility to connect to a server. For example, if your site has a local network running TCP/IP but no connection to the Internet, you can not use IRC. If you site has an Internet connection but no IRC server on the local network, you will need to connect to a server outside it, but many sites explicitly inhibit non-local connections for certain machines. In that case, you should *politely* (!!!) ask your network administrator for lifting that restriction. (Usually the reason for such restrictions is users, especially on PCs open to the 'public' e.g. in university computing centers, abusing network access for FTPing large amounts of data from the other end of the world. Restricting network access is in fact the only way of dealing with this problem, but maybe there is a person willing to start a local and therefore reachable IRC server. :-)
Some sites still are reluctant to allow the use of IRC because of fear that it may put too much load on the network. This is usually not the case, however, and you should try to settle the case with the responsibles using reasonable arguments.
Note that not all servers allow all clients in. When you get a message about being rejected by the server, you should find another server. All servers are part of the same network and have the same information, persons and channels.
ircle Windows and Messages
--------------------------
The first window you will see after successfully calling a server is called the message window. You will recognize it by its title: it is your nickname. The server will give you a few lines of welcome and "MOTD" messages. Then, at the bottom of the screen, there is a small box containing two lines of Monaco-9 called the status/input window. (In fact *this* window pops up first.) Everything you type on the keyboard will appear in the input line, and it will be processed on hitting the Return key. Above is the status line giving general information about you and the server:
Mister talking to #Hmgpf noc.belwue.de Flsh Log FT(1) 10:31:12
'Mister' - your nick
'#Hmgpf' - current target to wich mesages are sent
'noc.belwue.de' - your server. Will be replaced by status messages if not connected or errors occur.
'Flsh' will appear when you are flushing messages (see below on menus).
'Log' will appear when you are logging messages to a file.
'FT(n)' indicates that n DCC file transfers are in progress.
The input line is the most non-Mac-like thing in ircle but this is influenced by the fact that other IRC clients use a similar input line. You can place the input cursor with the mouse (one click will not suffice as it first activates the window) and move it with the cursor keys. The up/down keys allow for recalling the last entered lines (limited to 5000 chars).
IRC conversation is done by 'channels' and 'private messages'. Channels have names beginning with a # character. (Sometimes there are chanels beginning with a & character, these are local to your server.) You can list the channels currently in use with the /list command. When you join a channel (with the /join command), all messages you type get sent to all people on that channel, and you will see all messages by that persons in the form
<grumbl> Is anybody out there?
In ircle every channel corresponds to a window. When you join a channel, a new window will pop up having the name of that channel. It will present you with a topic (if set) and a list of people on that channel.
Private messages are exchanged between to people. They appear in the window like
*bubbl* Where is Prof. Smith tomorrow?
and the window they appear in is usually the frontmost window, regardless of the channel(s) the sender is on, unless there is a query window for that nick. It is intended that private messages are exchanged via query windows. They are opened with the /query command and look like channel windows with a nickname as title. Conversation between you and that nickname is done via private messages.
There is a third means of conversation, the DCC CHAT connection, which is a window with a title consisting of a nick surrounded by = signs. See below on DCC CHAT.
A NOTICE is a message that is generated as automated response to certain commands by servers or other client programs (but may be sent by users, too). It looks like
-uni-karlsruhe.de- This is the University of Karlsruhe, Germany.
Watch out for messages in the message window of the form
/WORD/sender/target/arguments/ or
/NUM/sender/target/arguments/, where NUM is a 3-digit number.
The former are generated by servers sending erroneous commands to a client (which should not happen, but as every program, the server may contain bugs), the latter are normal status messages that should be processed by the client but are not because of implementor's laziness. Somebody could tell me if such things occur. (By now, every defined numeric message is processed correctly by ircle, so this should not happen.)
You can obtain a window full of helpful information by giving a /help command or via the About box.
When you close a channel window you will leave the channel. Closing a query window or the help window will do nothing more than closing the window, and closing a DCC CHAT window will close that connection. Closing the message window will merely hide it until a message appears in it.
All windows can hold up to 20000 characters' worth of messages. If this number is exceeded, 5000 characters from the top will be deleted, so you always have access to at least the most recent 15000 characters of that conversation. You can mark text in a window with the mouse and Copy it via the Edit menu to the clipboard for further use.
Commands
----------
Having completed a line of input, you let it be processed by hitting the Return key. Then it is determined if the line consists of a command or a message. Commands are lines which start with the / (slash) character followed by the command name and optional parameters, e.g.
/join #tuebingen
(this is the command that will get you on a channel).
Messages are everything not starting with a slash. Messages are sent to the frontmost window, more precise to that (channel or query or DCC CHAT connection) that runs over the frontmost window, the message type and target being determined by the window type and name.
And here is a list of IRC commands (given in lowercase letters, but they are not case-sensitive, as nicks and channel names are not either):
/admin name - give administrative info about the specified server (which may be a server name or a nick, in the latter case giving info about that user's server). This always should at least include an E-Mail address of a person responsible for that server, to be contacted if problems occur.
/away message - marks you as being away, which will display a 'G' (gone) instead of 'H' (here) in the /who command and the specified message on /whois and private messages. /away without argument removes the away status.
/broadcast message - send message to all channels you're on and to all users you have queried.
/bye (text) - quit IRC after sending the optional text to all channels you're on. /quit, /exit or /signoff will do as well.
/cmdchar x - change command-prefix character. That means, subsequently commands must be prefixed with the given character instead of the /. Useful on certain keyboards...
/cping nick - measure the time it takes to send a message between you and "nick". This makes use of the CTCP protocol and does not work on every client.
/ctcp target command - perform the Client-To-Client-Protocol. This is supported only by modern clients and not vital, but has some useful functions. 'target' should be a nickname, to whom the command is sent. The user does not see the message, but his client program responds (usually) with a NOTICE containing an answer. See below on CTCP commands.
/date server - display date and time as seen by the specified server. /time is the same.
/dcc command nick - perform Direct-Client-Connection functions. These are supported only by modern clients, when in doubt use /ctcp clientinfo first. See below.
/help - pop up a window with helpful information, including a list of commands with short descriptions.
/ignore pattern - mark specific users to be ignored. Messages from them will not be displayed on your windows. If you feel harrassed by someone, this should be the first thing to do. 'pattern' may be of the form nick!user@host and may contain the ? and * wildcards, matching any character or any sequence of characters, respectively.
user and host are the ones given by /whois. If either no nick or no user@host is provided, a * will be inserted for the missing parts.
/ignore without parameters lists all ignore patterns currently in effect.
/ignore -pattern removes a pattern, which must be exactly the same as given in the list.
/ignore +pattern causes a user to not just be ignored but answered by a NOTICE to each message. (This may be considered rude by some people, but there are client programs which have this feature built-in with no choice.) Note that having many ignore patterns may slow down the program.
/info - display info about IRC and your server.
/invite nick channel - invite person to a channel. For invite-only channels (see /mode), this is the only way to join a channel.
/join channel - join a channel. Channel names always start with # or & character. If no window comes up after this, there may be a connection or server-related problem. /join without an argument joins the channel you were last /invite'd to. /channel is an alias for /join.
/kick channel nick - kick a person from channel (can only be done by channel operators). The victim may re-join unless banned (see /mode).
/kill nick - remove nick from the IRC network completely. This command can only be used by operators and should really not be used at all.
/leave channel - leave a channel. On ircle this is equivalent to closing a channel window. /part will do, too.
/links server - show server connections. (Warning: Long list to come!) Useful for operators only.
/list [par] [channel] - show channel name, number of users and topic. Without argument, lists all channels. Additional parameters may be given as follows, starting with a - (dash):
-min n - list only channels with a minimum of n users
-max n - list only channels with a maximum of n users
-local - list only local (&) channels
-global - list only global (#) channels
-public - list only public channels
-private - list only private channels (of dubious use)
-topic - list only channels with topic
/lusers - show statistics on the users on the network.
/me action - send an action description.
Example: /me switches off the air conditioning. This will be presented to other users on the channel as
Mister switches off the air conditioning.
with 'Mister' replaced by your nickname. There are some contrary opinions about this being necessary, but I did it because the actual implementation is shorter than this paragraph. Note that this uses CTCP protocol which is not recognized by older clients. You should end the sentence with a period.
/mode channel par - set a channel mode. 'par' can be +x (sets flag x), +x nick (sets flag x on nick), -x or -x nick removes flag, respectively. More than one flag may be given at once. The flags are (server version 2.7):
p - private channel (name not made public)
s - secret channel (never listed)
i - invite-only channel
m - moderated channel
t - only channel operators may set topic
n - only persons on channel can send messages to channel
l max - limit channel to max. # of users
b nick - ban nick (nick may not enter; instead of nick you can use nick!user@host with wildcards)
o nick - nick is channel operator
v nick - let nick talk on moderated channel
k key - set channel password
/mode can be set by channel operators only.
/mode nick par - set a user mode. The modes are:
i - invisible, meaning "not being listed with /who"
s - receive server notices
w - receive wallops messages
/motd server - show server's message of the day.
/msg nick message - send nick a private message. This can be done more easily via /query too.
/names channel - give a list of names on the channel. 'channel' may contain wildcards.
/nick newnick - change your nickname. This must be done if the server rejects your nickname.
/notice target text - send a NOTICE, which is just like a normal message ('target' may be a channel or nick) except that it may not generate automated responses. (This rule is to prevent loops, as automated responses of any kind are NOTICEs.)
/notify nick - add nick to the notification list. Whenever someone on this list signs on or off, you'll be informed about this fact. (This notification may be delayed a bit.) You can remove a nick from this list with /notify -nick.
/query nick - open a query window. What is sent to that window will become a private message to the specified nick. /query without an argument will query the person who sent you the last private message.
/server host port - switch to a different server. Used when your server goes down.
/show comm status - enable/disable display of messages resulting from certain commands. comm is one of: join, part, quit, topic, invite, nick, mode, kick, names or "all" meaning all of these; status is ON or OFF. These is of use on crowded channels to avoid seeing all the join and part messages, etc.
/summon user server - summon specified user to IRC. This will work only if the specified host is running a server and has this feature enabled. Otherwise, a Talk program will do too :-)
/topic channel text - set the channel topic.
/type - type a text file to the current chanel. You will be presented a file selection box. The contents of the file are sent in the background, one line at a time as if typed (usually rather slow - no bug but feature). Note that dumping large files to a channel without being asked to do so is considered bad behaviour. If simply a file transfer is to be done, you better use /dcc send - it's more efficient.
/users server - show users logged on to the server (like rwho, or finger, or similar).
/version server - show server version.
/wallops text - sends text to all IRC operators online. This command is obsolete and won't be accepted by modern servers. If you want to talk to operators specifically, /join #Twilight_Zone instead. (And don't harrass them too much, most of them have work to do.)
/who channel - list users on channel. Without an argument, the current channel is assumed. When talking no channel, all IRC users are listed (very long list!)
/whois nick - gives detailed information about a user, specifically which login name on which machine he is and what he has entered as his real name. Sometimes this information is useless because the user may be using a 'public client' or a Mac or MSDOS box which has no login names. In this case you will get bogus names or raw IP addresses instead of an account usable as E-Mail address. In case the other part is using ircle, you can get more information with /ctcp finger (s.b.)
/whois without an argument will use the nick who sent you the last message or joined most recently a channel.
/whowas nick - like /whois but displays information of users that have signed off recently.
Note that commands for the exclusive use by operators are not all mentioned here. They should know them anyway. :-)
CTCP and DCC
------------
/ctcp nick command sends a special message containing a command, which will be processed by the other part's client program. Some clients do not support this.
'command' may be:
clientinfo - list all known CTCP commands along with description. If you get no answer on this, the other part has CTCP and DCC not implemented.
finger - gives user information. If the other part uses a Unix client, this will respond with the information returned by the finger command. If the other part is using ircle, this will return the E-Mail address the user has entered in the preferences field. Provided this address is valid, it can be used for mailing him or launching a finger, which will not work with the information returned by /whois. It also returns the idle time (in seconds) of the user, big numbers usually indicating the user being away or not caring.
time - tells the other part's local time.
version - tells which client version and environment the other part is using.
action - is used by the /me command.
ping - is used by the /cping command.
dcc - is used by the /dcc command, NOT by the user - this could confuse the client.
Clients may implement other CTCP commands as well which they will tell on the clientinfo command. Commands which are responded generate a NOTICE with the original command and the response text in it.
The Direct-Client-Connection (DCC) protocol establishes connections between clients, bypassing the server network for efficiency or security reasons. It is invoked by /dcc command nick.
'command' may be:
chat - opens a DCC CHAT connection to nick. Messages exchanged via this connection are not sent over IRC but directly to the other client. Therefore this is the most secure method of communication, as nobody even with a 'hacked' or bogus server can even accidentally see it. (But be aware that there just is no method of tap-proof communication on the Internet, though.)
send, tsend - transfers a file. You will be presented a file select box. The file will be sent over a direct connection to the other part. For Macintosh files, this will transfer the data fork only, so to transfer programs or other files with resource fork you have to BinHex them. (this is the same problem as with FTP; in fact /dcc send is just a convenient replacement for FTP, working almost the same way.) If the file contains text, you should use tsend instead of send, which will convert the file to ISO charset (see below) with LFs instead of CRs (this is what Un*x clients use). send will send the file unchanged (binary mode). File transfer runs in the background without disturbing communication (well, slowing down a big bit :-)
get, tget - accept an incoming file transfer. When you get a message for a DCC SEND request, you should answer with /dcc get nick, which will receive the offered file after you have selected a name for it with the usual file selector. Use tget if the file is a text file (s.a.)
close type nick - abandon a DCC connection.
/dcc without parameters will list all DCC connections currently in effect. No two connections of the same type to the same nick may be in effect at one time; before re-opening a failed connection you have to close it.
Other DCC commands present in other clients are not implemented. For TALK there is already a wonderful program for the Macintosh (by Peter Lewis) which you can use instead.
Each DCC request must be answered by the other part. If this is not done, the connection will not be established. How the answer is done depends on the client. With ircle, a CHAT request is to be answered with a CHAT, and a SEND request to be answered with a GET.
NOTE that for DCC to work, TCP/IP connections between the two clients have to be established. This may be technically impossible due to the reasons mentioned above under 'Servers', and connections may fail because of bad links even with the server connection remaining up. In such cases you will get an error message.
------ Continue reading with ircle Users Manual part 2 ------
